Feat | Add OpenAPI documentation for OAuth2GroupApiController by matiasperrone-exo · Pull Request #109 · OpenStackweb/openstackid

matiasperrone-exo · 2026-02-11T21:42:35Z

Task:

Ref: https://app.clickup.com/t/86b8e6jrj

Endpoints:

Method	Endpoint	Method Name
GET,HEAD	api/v1/groups	getAll

Summary by CodeRabbit

Documentation
- Enhanced API documentation and specifications for the Groups API endpoints, including detailed endpoint schemas, parameters, and security requirements.

martinquiroga-exo

LGTM

@matiasperrone-exo please add the clickup card link to this PR.

caseylocker

Move #[OA\Get] from the class to getAllSerializerType() — Follow the pattern in OAuth2UserApiController where the annotation sits on getAllSerializerType(), not on the class declaration.
Use the existing user_oauth2 security scheme instead of creating OAuth2GroupsSecurity — user_oauth2 already covers Groups. Add IGroupScopes::ReadAll and IGroupScopes::Write to the scopes in
app/Swagger/Security/UsersOAuth2Schema.php and reference user_oauth2 in the endpoint annotation. Remove OAuth2GroupApiControllerSecuritySchema.php.
Document the lack of route middleware — GET /api/v1/groups has no middleware in routes/api.php. The description field should note this (e.g., "No route-level middleware enforcement; requires valid OAuth2 bearer
token only.").

matiasperrone-exo · 2026-02-24T19:33:42Z

Bullets 1 and 3 were incorporated:

Move #[OA\Get] from the class to getAllSerializerType() — Follow the pattern in OAuth2UserApiController where the annotation sits on getAllSerializerType(), not on the class declaration.

Document the lack of route middleware — GET /api/v1/groups has no middleware in routes/api.php. The description field should note this (e.g., "No route-level middleware enforcement; requires valid OAuth2 bearer
token only.").

I have some questions regarding your comment (2nd bullet):

Use the existing user_oauth2 security scheme instead of creating OAuth2GroupsSecurity — user_oauth2 already covers Groups. Add IGroupScopes::ReadAll and IGroupScopes::Write to the scopes in
app/Swagger/Security/UsersOAuth2Schema.php and reference user_oauth2 in the endpoint annotation. Remove OAuth2GroupApiControllerSecuritySchema.php.

This PR does not have UsersOAuth2Schema present, if I disregard that issue, are you sure you want to use the scopes from Users into Groups?

Taking into account that one comes from App\libs\OAuth2\IUserScopes and the this one (OAuth2GroupsSecurity) from App\libs\OAuth2\IGroupScopes.

If you are sure I will make the change.

caseylocker · 2026-02-25T20:54:18Z

Bullets 1 and 3 were incorporated:

Move #[OA\Get] from the class to getAllSerializerType() — Follow the pattern in OAuth2UserApiController where the annotation sits on getAllSerializerType(), not on the class declaration.

Document the lack of route middleware — GET /api/v1/groups has no middleware in routes/api.php. The description field should note this (e.g., "No route-level middleware enforcement; requires valid OAuth2 bearer
token only.").

I have some questions regarding your comment (2nd bullet):

Use the existing user_oauth2 security scheme instead of creating OAuth2GroupsSecurity — user_oauth2 already covers Groups. Add IGroupScopes::ReadAll and IGroupScopes::Write to the scopes in
app/Swagger/Security/UsersOAuth2Schema.php and reference user_oauth2 in the endpoint annotation. Remove OAuth2GroupApiControllerSecuritySchema.php.

This PR does not have UsersOAuth2Schema present, if I disregard that issue, are you sure you want to use the scopes from Users into Groups?

Taking into account that one comes from App\libs\OAuth2\IUserScopes and the this one (OAuth2GroupsSecurity) from App\libs\OAuth2\IGroupScopes.

If you are sure I will make the change.

That's a valid callout. Keep #2 as is.

caseylocker

LGTM

…ler v1 routes

coderabbitai · 2026-03-17T19:30:05Z

📝 Walkthrough

Walkthrough

This pull request adds OpenAPI documentation annotations to the OAuth2 Groups API endpoint, including new schema definitions for paginated group responses and security configurations. No changes to existing API logic or method signatures.

Changes

Cohort / File(s)	Summary
API Controller Documentation `app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php`	Adds OpenAPI annotations to the getAll endpoint, including path, parameters (page, per_page, filter, order), HTTP responses (200, 401, 403, 404, 412, 500), and required imports for IGroupScopes and OA.
Swagger Schema Definitions `app/Swagger/OAuth2GroupApiControllerSchemas.php`, `app/Swagger/Models/GroupSchema.php`	Introduces PaginatedGroupResponseSchema class composing PaginateDataSchemaResponse with a data array of Group items; minor formatting adjustment in GroupSchema.
Swagger Security Schema `app/Swagger/Security/OAuth2GroupApiControllerSecuritySchema.php`	Adds OAuth2GroupApiControllerSecuritySchema class defining OAuth2 securityScheme with authorizationCode flow and group-related scopes (ReadAll, Write).

Poem

🐰 Our schemas now gleam with OpenAPI light,
Documentation blooms where the security's tight,
Groups march through endpoints, all properly bound,
With paginated responses and safe passage found! ✨

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding OpenAPI documentation for the OAuth2GroupApiController, which aligns with the changeset's additions of OA annotations and schema classes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings (stacked PR)
📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/openapi----api-v1---oauth2groupapicontroller

📝 Coding Plan

Generate coding plan for human review comments

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

matiasperrone-exo · 2026-03-17T19:30:06Z

Rebased

github-actions · 2026-03-17T19:31:29Z

📘 OpenAPI / Swagger preview

➡️ https://OpenStackweb.github.io/openstackid/openapi/pr-109/

This page is automatically updated on each push to this PR.

coderabbitai

🧹 Nitpick comments (1)

app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php (1)

49-51: Consider documenting the HEAD endpoint.

The PR objectives mention both GET and HEAD endpoints are mapped to getAll. While HEAD behavior typically mirrors GET (returning only headers), you may want to add an OA\Head annotation for completeness if the API explicitly supports HEAD requests.

📝 Optional: Add HEAD annotation

#[OA\Head(
    path: '/api/v1/groups',
    operationId: 'headGroups',
    summary: 'Check groups endpoint',
    description: 'Returns headers only for the groups endpoint.',
    security: [['OAuth2GroupsSecurity' => [IGroupScopes::ReadAll]]],
    tags: ['Groups'],
    responses: [
        new OA\Response(response: Response::HTTP_OK, description: 'Endpoint available'),
        new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: 'Unauthorized'),
    ]
)]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php` around lines 49
- 51, Add an OA\Head annotation for the '/api/v1/groups' endpoint to document
the HEAD method (mapped to the existing controller method getAll) so tooling
shows HEAD support; include operationId 'headGroups', a brief
summary/description, the same security entry as GET (IGroupScopes::ReadAll), the
'Groups' tag, and minimal responses (HTTP_OK and HTTP_UNAUTHORIZED) to mirror
GET's contract.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php`:
- Around line 49-51: Add an OA\Head annotation for the '/api/v1/groups' endpoint
to document the HEAD method (mapped to the existing controller method getAll) so
tooling shows HEAD support; include operationId 'headGroups', a brief
summary/description, the same security entry as GET (IGroupScopes::ReadAll), the
'Groups' tag, and minimal responses (HTTP_OK and HTTP_UNAUTHORIZED) to mirror
GET's contract.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4a104c78-dbf9-4f6d-850f-51c87c875d37

📥 Commits

Reviewing files that changed from the base of the PR and between 6d23f7f and 4693c58.

📒 Files selected for processing (4)

app/Http/Controllers/Api/OAuth2/OAuth2GroupApiController.php
app/Swagger/Models/GroupSchema.php
app/Swagger/OAuth2GroupApiControllerSchemas.php
app/Swagger/Security/OAuth2GroupApiControllerSecuritySchema.php

matiasperrone-exo added the documentation Improvements or additions to documentation label Feb 11, 2026

matiasperrone-exo self-assigned this Feb 11, 2026

matiasperrone-exo force-pushed the feat/openapi----api-v1---oauth2groupapicontroller branch 2 times, most recently from 25a4f67 to 853feef Compare February 12, 2026 19:19

matiasperrone-exo mentioned this pull request Feb 12, 2026

Feature | Add OpenAPI documentation controller OAuth2UserApiController v2 routes #105

Merged

smarcet force-pushed the main branch 2 times, most recently from ae79f5e to 4b5b726 Compare February 12, 2026 20:00

matiasperrone-exo force-pushed the feat/openapi----api-v1---oauth2groupapicontroller branch 4 times, most recently from 28dad35 to 04d4dab Compare February 18, 2026 21:08

martinquiroga-exo approved these changes Feb 18, 2026

View reviewed changes

matiasperrone-exo force-pushed the feat/openapi----api-v1---oauth2groupapicontroller branch 2 times, most recently from d4856c2 to 16a5eb6 Compare February 19, 2026 21:01

caseylocker requested changes Feb 22, 2026

View reviewed changes

matiasperrone-exo requested a review from caseylocker February 24, 2026 19:34

caseylocker approved these changes Feb 25, 2026

View reviewed changes

matiasperrone-exo added 2 commits March 17, 2026 19:29

feat: Add OpenAPI documentation annotations for OAuth2GroupApiControl…

add6636

…ler v1 routes

chore: Add PR requested changes bullets 1 and 3

4693c58

matiasperrone-exo force-pushed the feat/openapi----api-v1---oauth2groupapicontroller branch from 5c100aa to 4693c58 Compare March 17, 2026 19:29

coderabbitai bot reviewed Mar 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat | Add OpenAPI documentation for OAuth2GroupApiController#109

Feat | Add OpenAPI documentation for OAuth2GroupApiController#109
matiasperrone-exo wants to merge 2 commits intomainfrom
feat/openapi----api-v1---oauth2groupapicontroller

matiasperrone-exo commented Feb 11, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

martinquiroga-exo left a comment

Uh oh!

caseylocker left a comment

Uh oh!

matiasperrone-exo commented Feb 24, 2026

Uh oh!

caseylocker commented Feb 25, 2026

Uh oh!

caseylocker left a comment

Uh oh!

coderabbitai bot commented Mar 17, 2026 •

edited

Loading

Walkthrough

Changes

Poem

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

matiasperrone-exo commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

coderabbitai bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

matiasperrone-exo commented Feb 11, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Task:

Endpoints:

Summary by CodeRabbit

Uh oh!

martinquiroga-exo left a comment

Choose a reason for hiding this comment

Uh oh!

caseylocker left a comment

Choose a reason for hiding this comment

Uh oh!

matiasperrone-exo commented Feb 24, 2026

Uh oh!

caseylocker commented Feb 25, 2026

Uh oh!

caseylocker left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Poem

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

matiasperrone-exo commented Mar 17, 2026

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matiasperrone-exo commented Feb 11, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 17, 2026 •

edited

Loading